들어가며

AI에게 코드를 맡겼을 때 결과가 마음에 들지 않는 경우, 원인을 따라가 보면 모델이 코드를 못 짜서인 경우는 생각보다 드물었습니다.

대부분은 제가 준 정보가 불완전했고, 그 사실을 저도 몰랐다는 쪽이었습니다. 요구사항을 다 말했다고 생각했는데 정작 중요한 전제를 빼먹었거나, 아예 고려조차 못 한 케이스가 구현 중반에 튀어나오는 식입니다.

그래서 워크플로우를 하나 짰습니다. 핵심은 단순합니다.

코드를 짜기 전에, 무엇을 모르는지부터 문서로 만든다.

전체 그림

네 단계입니다.

task 생성 → 작업을 위한 정확한 지도 생성 → auto work → PR 생성

앞의 두 단계에서는 코드를 단 한 줄도 건드리지 않습니다. 이게 이 워크플로우의 가장 중요한 제약입니다.

1단계. task 생성

목적을 전달한다

먼저 유저가 클로드에게 목적을 전달합니다.

이번 목적은 리뷰 작성 페이지의 % 표기 오류를 수정하는 것

이 정도로 시작합니다. 이 시점에는 대충 말해도 됩니다. 어차피 다음 단계에서 캐물을 것이기 때문입니다.

클로드가 사전 질문을 한다

클로드는 목적에 맞춰 간결한 사전 질문을 던집니다.

• 목적의 제목과 내용을 간결하게 설명해주세요
• 이 목적으로 수정되어야 하는 레포지토리의 범위를 알려주세요
• 관련된 Linear 링크를 알려주세요
• 관련된 Google Chat 링크를 알려주세요
• 관련된 Notion 링크를 알려주세요
• 관련된 Figma 링크를 알려주세요
• 기타 관련된 링크를 알려주세요
• 이 task가 종료되었을 때의 기대값을 설명해주세요

링크를 이렇게 잘게 나눠 묻는 데는 이유가 있습니다. “관련 자료 주세요”라고 한 번에 물으면 보통 제일 먼저 떠오르는 것 하나만 줍니다. 항목을 쪼개서 물으면 “아, 그러고 보니 피그마가 있었지” 가 나옵니다.

마지막 기대값 질문이 특히 중요합니다. 이게 없으면 나중에 “다 됐다”의 기준이 없습니다.

task 문서를 만든다

클로드는 답변을 받아 work/task 폴더 아래에 마크다운 문서를 생성합니다.

각 task 문서는 다음 메타데이터를 가집니다.

상태는 이렇게 흐릅니다.

생성 → 작업대기 → 작업완료 → 수정필요 ↺
                          └→ 완료

2단계. 작업을 위한 정확한 지도 생성

여기가 이 워크플로우의 본체입니다.

먼저 읽는다

클로드는 유저가 첨부한 링크와 옵시디언 볼트, 그리고 기존 레포지토리의 코드 구조를 파악합니다.

그 다음 유저와 질의응답을 거쳐 작성될 코드 구조의 지도를 밝힙니다.

네 개의 칸

task 폴더의 문서에는 반드시 다음 네 가지가 적혀 있어야 합니다.

이 네 칸이 이 워크플로우를 만든 이유입니다.

보통 우리가 AI에게 주는 건 a뿐입니다. 그런데 실제로 구현을 망가뜨리는 건 b, c, d입니다.

• b는 내 머릿속에는 있는데 말로 안 나온 것입니다. “당연히 그렇게 하는 거 아니야?”가 여기 있습니다.
• c는 어딘가에 적혀 있지만 아무도 이 대화에 가져오지 않은 것입니다.
• d는 아무도 생각해본 적 없는 것입니다.

특히 d가 이 워크플로우의 존재 이유입니다. a, b, c는 시간이 걸릴 뿐 결국 채워집니다. 하지만 d는 명시적으로 드러내지 않으면 구현이 절반쯤 진행됐을 때 터집니다. 그때는 이미 설계가 그 위에 얹혀 있습니다.

네 칸을 유저와 클로드가 질의응답으로 채우고 나면 다음으로 넘어갑니다.

사각지대 점검

칸을 다 채웠다고 끝이 아닙니다. 두 가지 검증을 겁니다.

첫째, 병렬 점검. 정말 빠진 부분이 없는지, 잘못 오탐한 부분은 없는지 3개의 에이전트가 병렬로 체크합니다. 빠뜨린 것만 찾는 게 아니라 잘못 넣은 것도 찾습니다. 없는 문제를 만들어놓고 거기에 맞춰 설계하는 게 더 위험하기 때문입니다.

둘째, 역질문. task 문서를 기반으로 클로드가 유저에게 거꾸로 질문합니다. 목적과 결과, 과정과 코드가 정확하게 설계되었는지 확인하는 절차입니다.

방향이 뒤집힌다는 게 핵심입니다. 지금까지는 제가 설명하고 클로드가 이해했는데, 여기서는 클로드가 묻고 제가 대답합니다. 제가 이해하지 못한 부분이 여기서 드러납니다.

완성된 task 문서

점검이 끝난 task 문서는 다음을 담고 있어야 합니다.

• 제목과 목적
• 설계 주요 내용
• 네 개의 칸에 대한 내용
• 구현 예정 노트
• 반드시 지켜야 하는 규칙 목록 — 해당 레포지토리의 CLAUDE.md 룰을 확인해서 정리합니다.
  • 예) core-front의 컴포넌트는 공통 디자인 라이브러리를 우선 사용한다
• 수정될 파일 목록 — 어떤 식으로 수정될지에 대한 예시와, 올바른 결과를 검증하기 위한 테스트 내지 테스트 코드 목록
• 수정 이후 변경사항과 사이드이펙트 확인 내용
• 실제 작업 log

유저가 완벽하게 이해를 마쳤다면 task 상태를 생성 → 작업대기로 변경합니다.

여기서 절대 코드를 건드리지 않는다

task 파일을 만드는 도중에는 절대 코드를 변경하거나 실제 코드를 수정하지 않습니다. 작업을 위한 task 파일을 만들 뿐입니다.

이 규칙을 명시적으로 넣은 이유가 있습니다.

계획하면서 조금씩 고치기 시작하면, 지도를 그리는 일과 길을 걷는 일이 섞입니다. 그러면 “이건 이미 반쯤 고쳤으니까”라는 이유로 검토가 느슨해지고, 결국 검증 없이 넘어간 코드가 남습니다.

계획 단계의 산출물은 문서 하나뿐이어야 합니다. 그래야 마음 편히 버릴 수 있습니다.

3단계. auto work

언제 시작하는가

1. work/task 폴더의 md 파일 중 상태가 작업대기인 task를 확인합니다.
2. 6시 30분 이후 작업대기 상태의 task를 모두 개발 진행합니다.

시간을 정해둔 이유는 단순합니다. 낮에는 지도를 그리고, 구현은 퇴근 후에 돌립니다. 사람이 붙어 있어야 잘 되는 일과 붙어 있지 않아도 되는 일을 시간으로 갈라놓은 것입니다.

어떻게 진행하는가

3. 작업은 작업 레포지토리에서 진행하며, main 브랜치 기준으로 신규 브랜치를 생성합니다. 브랜치명은 README에 적힌 컨벤션을 따릅니다.
4. 신규 브랜치로 체크아웃한 뒤 task md 파일을 읽어가며 실제 구현을 진행합니다.
5. 변경되거나 새로 생기는 파일에 대한 이력은 문서의 log 항목에 최대 100자까지 묶어 단위별로 적재합니다.
6. 구현 예정 노트와 실제 코드가 충돌하거나 에러가 발견되면, 구현 예정 노트의 기존 내용을 취소선 처리하고 업데이트하며 테스트 코드와 log에도 반영합니다.

6번이 개인적으로 마음에 드는 부분입니다. 틀린 계획을 지우지 않고 줄만 그어서 남겨둡니다.

- ~~ReviewRate 컴포넌트에서 toFixed(1) 적용~~
- 서버가 이미 소수점 처리해서 내려주고 있었음. 포맷은 유틸로 분리

이렇게 남겨두면 나중에 “내 예측이 어디서 틀렸는가” 를 볼 수 있습니다. 결과만 남은 문서는 다음 task를 더 잘 설계하는 데 도움이 되지 않습니다.

7. 구현은 최대 10개의 멀티 에이전트가 진행합니다. 구현 시 에이전트는 알맞은 스킬을 사용합니다.
8. Figma MCP 또는 Figma 링크에서 디자인을 확인하고, 실제 구현된 디자인과 최대 3번 교차검증하여 UI가 잘 구현되었는지 확인합니다.
   • core-front 같은 경우 공용 라이브러리를 먼저 사용합니다.
   • 단, UI가 크게 중요하지 않거나 디자인이 미첨부인 경우는 건너뜁니다.

구현 루프

9. 커밋은 구현 단위로 묶어서 진행하며, 다음 루프를 돕니다.

구현 → 테스트 → 교차검증 및 코드리뷰 → 에러·누락 확인 → 재구현

교차검증 단계에서 보는 것은 “task 파일의 결과가 제대로 구현되었는가” 입니다. 코드가 동작하는지가 아니라, 애초에 하기로 한 일이 됐는지를 봅니다. 기준이 문서에 이미 적혀 있으니 가능한 검증입니다.

루프는 최대 30회까지 돌되, 중간에 작업이 완료되면 종료합니다. 30회는 완주 목표가 아니라 폭주 방지선입니다.

4단계. PR 생성

10. 마지막으로 PR을 생성합니다. 이때도 README의 컨벤션을 확인해 맞춥니다.

PR 본문은 다음 네 항목으로 고정했습니다.

문서에 Linear가 연결되어 있다면 PR 제목에 괄호로 Linear 번호를 적습니다.

fix: 리뷰 작성 페이지 % 표기 오류 수정 (CORE-123)

원인과 확인필요를 고정 항목으로 넣은 게 핵심입니다.

“무엇을 바꿨다”는 diff를 보면 알 수 있습니다. 하지만 왜 그런 문제가 있었는지는 작업한 사람만 압니다. 그리고 확인필요는 자동화된 구현에서 특히 중요합니다. 에이전트가 확신하지 못한 부분을 사람 눈으로 볼 지점으로 명시해두는 자리이기 때문입니다.

정리

만들고 나서 보니, 이 워크플로우가 실제로 하는 일은 AI에게 코드를 잘 짜게 만드는 것이 아니었습니다.

내가 무엇을 모르는지 알아내게 만드는 것에 가까웠습니다.

• 사전 질문은 말하지 않은 것을 꺼내게 합니다
• 네 개의 칸은 모른다는 사실 자체를 문서에 자리로 만들어둡니다
• 사각지대 점검과 역질문은 그 문서가 정말 맞는지 반대 방향에서 봅니다
• 코드 금지 규칙은 이 과정을 건너뛰지 못하게 막습니다

구현은 그 다음 일입니다. 지도가 정확하면 걷는 건 에이전트 열 개가 밤에 해도 되고, 지도가 부정확하면 아무리 좋은 모델을 써도 엉뚱한 곳에 도착합니다.

한동안 돌려보고 부족한 부분을 다시 정리해보려 합니다.